package com.gitee.helioz.openai.api.endpoint.finetunes;

import com.gitee.helioz.openai.api.dto.DeleteResponse;
import com.gitee.helioz.openai.api.dto.finetune.FineTuneCreateRequest;
import com.gitee.helioz.openai.api.dto.finetune.FineTuneEventsResponse;
import com.gitee.helioz.openai.api.dto.finetune.FineTuneListResponse;
import com.gitee.helioz.openai.api.dto.finetune.FineTuneResponse;

/**
 * 〈微调服务〉
 *
 * @author <a href="https://gitee.com/helioz">Morning Starr</a>
 */
public interface FineTuneService {

    /**
     * 创建一个用于微调（fine-tune）模型的训练任务
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/create">文档</a></p>
     *
     * @param createRequest 请求对象
     * @return 响应对象
     */
    FineTuneResponse create(FineTuneCreateRequest createRequest);

    /**
     * 微调（fine-tune）模型的训练任务集合
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/list">文档</a></p>
     *
     * @return 响应对象
     */
    FineTuneListResponse list();

    /**
     * 获取微调（fine-tune）模型的训练任务信息
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/retrieve">文档</a></p>
     *
     * @param fineTuneId 微调任务ID
     * @return 响应对象
     */
    FineTuneResponse retrieve(String fineTuneId);

    /**
     * 取消微调（fine-tune）模型的训练任务
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/cancel">文档</a></p>
     *
     * @param fineTuneId 微调任务ID
     * @return 响应对象
     */
    FineTuneResponse cancel(String fineTuneId);

    /**
     * 获取指定微调任务的细粒度状态更新
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/events">文档</a></p>
     *
     * @param fineTuneId 微调任务ID
     * @param stream 微调任务ID  可选参数，默认值为false。
     * 是否以流式方式获取Fine-tune作业的事件。如果设置为true，则事件将作为仅包含数据的服务器推送事件（Server-Sent Events）在可用时发送。
     * 当作业完成（成功、取消或失败）时，流将以data: [DONE]消息终止。如果设置为false，则只会返回到目前为止生成的事件。
     * @return 响应对象
     */
    FineTuneEventsResponse events(String fineTuneId, boolean stream);

    /**
     * 删除微调（fine-tune）模型
     * <p><a href="https://platform.openai.com/docs/api-reference/fine-tunes/delete-model">文档</a></p>
     *
     * @param model 要删除的 Fine-tune 模型的名称或 ID
     * @return 响应对象
     */
    DeleteResponse delete(String model);
}
